home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus 2000 #4 / Amiga Plus CD - 2000 - No. 4.iso / Tools / Commo-Support / Disk-Archive / includes-1_4.dms / includes-1_4.adf / doc.zoo / timer.doc < prev    next >
Encoding:
Text File  |  1989-12-01  |  9.8 KB  |  392 lines
  1.  
  2.  
  3. TABLE OF CONTENTS
  4.  
  5. timer.device/--background--
  6. timer.device/AbortIO()
  7. timer.device/AddTime()
  8. timer.device/CmpTime()
  9. timer.device/GetSysTime()
  10. timer.device/ReadEClock()
  11. timer.device/SubTime()
  12. timer.device/TR_ADDREQUEST
  13. timer.device/TR_GETSYSTIME
  14. timer.device/TR_SETSYSTIME
  15.  
  16.  
  17. timer.device/--background--                         timer.device/--background--
  18.  
  19.    TIMER REQUEST
  20.     A time request is a non standard IO Request.  It has an IORequest
  21.     followed by a timeval structure or an eclockval structure.
  22.  
  23.    TIMEVAL
  24.     A timeval structure consists of two longwords.  The first is
  25.     the number of seconds, the latter is the fractional number
  26.     of microseconds.  The microseconds must always be "normalized"
  27.     e.g. the longword must be between 0 and one million.
  28.  
  29.    ECLOCKVAL
  30.     A eclockval structure consists of two longwords.  The first is
  31.     the high order 32 bits of a 64 bit number and the second is the
  32.     the low order 32 bits.  The 64 bit number is a count of "E" clock
  33.     ticks.  The "E" clock frequency is related to the master clock
  34.     frequency of the machine and can be determined by calling the
  35.     ReadEClock() library like call.
  36.  
  37.    UNITS
  38.     The timer contains five units -- two designed to accuratly measure
  39.     short intervals, one that has little system overhead and is very
  40.     stable over time, and two that work like an alarm clock.
  41.  
  42.    UNIT_MICROHZ
  43.     This unit uses the programmable timers in the 8520s to keep track
  44.     of its time.  It has precision down to about 2 microseconds, but
  45.     will drift as system load increases.  The accuracy of this unit
  46.     is the same as that of the master clock of the machine.  This unit
  47.     uses a timeval in its timerequest.
  48.  
  49.    UNIT_VBLANK
  50.     This unit uses a strobe from the power supply to keep track of its
  51.     time or the "E" clock on machines without power supply strobes.
  52.     It is very stable over time, but only has a resolution of that of
  53.     the vertical blank interrupt.  This unit is very cheap to use, and
  54.     should be used by those who are waiting for long periods of time
  55.     (typically 1/2 second or more).  This unit uses a timeval in its
  56.     timerequest.
  57.  
  58.    UNIT_ECLOCK
  59.     This unit is exacly the same as UNIT_MICROHZ except that it uses
  60.     an eclockval instead of a timeval in its timerequest.
  61.  
  62.    UNIT_WAITUNTIL
  63.     This unit waits until the systime is greater than or equal to the
  64.     time in the timeval in the timerequest.  This unit has the same
  65.     resolution and accuracy as that of UNIT_VBLANK.
  66.  
  67.    UNIT_WAITECLOCK
  68.     This unit waits until the E-Clock value as returned by ReadEClock()
  69.     is greater than or equal to the eclockval in the timerequest. This
  70.     unit has the same resolution and accuracy as that of UNIT_ECLOCK.
  71.  
  72.    LIBRARY
  73.     In addition to the normal device calls, the timer also supports
  74.     several direct, library like calls.
  75.  
  76.    BUGS
  77.     In the V1.2/V1.3 release, the timer device has problems with
  78.     very short time requests.  When one of these is made, other
  79.     timer requests may be finished inaccurately.  A side effect
  80.     is that AmigaDOS requests such as "Delay(0);" or
  81.     "WaitForChar(x,0);" are unreliable. 
  82.  
  83.  
  84. timer.device/AbortIO()                                   timer.device/AbortIO()
  85.  
  86.    NAME
  87.     AbortIO -- Remove an existing timer request.
  88.  
  89.    SYNOPSIS
  90.     error = AbortIO( timerequest )
  91.     D0               A1
  92.  
  93.     LONG AbortIO( struct timerequest * );
  94.  
  95.    FUNCTION
  96.     This is an exec.library call.
  97.  
  98.     This routine removes a timerquest from the timer.  It runs in
  99.     the context of the caller.
  100.  
  101.    INPUTS
  102.     timerequest - the timer request to be aborted
  103.  
  104.    RETURNS
  105.     0  if the request was aborted, io_Error will also be set to
  106.         IOERR_ABORTED.
  107.     -1 otherwise
  108.  
  109.    NOTES
  110.     This function may be called from interrupts.
  111.  
  112.    SEE ALSO
  113.     exec.library/AbortIO()
  114.  
  115.    BUGS
  116.  
  117.  
  118. timer.device/AddTime()                                   timer.device/AddTime()
  119.  
  120.    NAME
  121.     AddTime -- Add one time request to another.
  122.  
  123.    SYNOPSIS
  124.     AddTime( Dest, Source )
  125.              A0    A1
  126.  
  127.     void AddTime( struct timeval *, struct timeval *);
  128.  
  129.    FUNCTION
  130.     This routine adds one timeval structure to another.  The
  131.     results are stored in the destination (Dest + Source -> Dest)
  132.  
  133.     A0 and A1 will be left unchanged
  134.  
  135.    INPUTS
  136.     Dest, Source -- pointers to timeval structures.
  137.  
  138.    NOTES
  139.     This function may be called from interrupts.
  140.  
  141.    SEE ALSO
  142.     timer.device/CmpTime(),
  143.     timer.device/SubTime()
  144.  
  145.    BUGS
  146.  
  147.  
  148. timer.device/CmpTime()                                   timer.device/CmpTime()
  149.  
  150.    NAME
  151.     CmpTime -- Compare two timeval structures.
  152.  
  153.    SYNOPSIS
  154.     result = CmdTime( Dest, Source )
  155.     D0                A0    A1
  156.  
  157.     LONG CmdTime( struct timeval *, struct timeval *);
  158.  
  159.    FUNCTION
  160.     This routine compares timeval structures
  161.  
  162.     A0 and A1 will be left unchanged
  163.  
  164.    INPUTS
  165.     Dest, Source -- pointers to timeval structures.
  166.  
  167.    RESULTS
  168.     result will be   0 if Dest has same time as source
  169.                     -1 if Dest has more time than source
  170.                     +1 if Dest has less time than source
  171.  
  172.    NOTES
  173.     This function may be called from interrupts.
  174.  
  175.    SEE ALSO
  176.     timer.device/AddTime(),
  177.     timer.device/SubTime()
  178.  
  179.    BUGS
  180.     Older version of this document had the sense of the return
  181.     codes wrong; the code hasn't changed but the document has.
  182.  
  183.  
  184. timer.device/GetSysTime()                             timer.device/GetSysTime()
  185.  
  186.    NAME
  187.     GetSysTime -- Get the system time. (V36)
  188.  
  189.    SYNOPSIS
  190.     GetSysTime( Dest )
  191.                 A0
  192.  
  193.     void GetSysTime( struct timeval * );
  194.  
  195.    FUNCTION
  196.     Ask the system what time it is.  The system time starts off at
  197.     zero at power on, but may be initialized via the TR_SETSYSTIME
  198.     timer.device command.
  199.  
  200.     System time is monotonocally increasing and guarenteed to be
  201.     unique (except when the system time is set back).
  202.  
  203.     A0 will be left unchanged.
  204.  
  205.     This function is less expensive to use than the TR_GETSYSTIME
  206.     IORequest.
  207.  
  208.    INPUTS
  209.     Dest -- pointer to a timeval structure to hold the system time.
  210.  
  211.    RESULTS
  212.     Dest -- the timeval structure will contain the system time.
  213.  
  214.    NOTES
  215.     This function may be called from interrupts.
  216.  
  217.    SEE ALSO
  218.     timer.device/TR_GETSYSTIME,
  219.     timer.device/TR_SETSYSTIME,
  220.  
  221.    BUGS
  222.  
  223.  
  224. timer.device/ReadEClock()                             timer.device/ReadEClock()
  225.  
  226.    NAME
  227.     ReadEClock -- Get the current value of the E-Clock. (V36)
  228.  
  229.    SYNOPSIS
  230.     E_Freq = ReadEClock( Dest )
  231.     D0                   A0
  232.  
  233.     ULONG ReadEClock ( struct EClockVal * );
  234.  
  235.    FUNCTION
  236.     This routine calculates the current 64 bit value of the E-Clock
  237.     and stores it in the destination EClockVal structure. The count
  238.     rate of the E-Clock is also returned.
  239.  
  240.     A0 will be left unchanged
  241.  
  242.     This is a low overhead function designed so that very short
  243.     intervals may be timed.
  244.  
  245.    INPUTS
  246.     Dest -- pointer to an EClockVal structure.
  247.  
  248.    RETURNS
  249.     Dest -- the EClockVal structure will contain the E-Clock time
  250.     E_Freq -- The count rate of the E-Clock (tics/sec).
  251.  
  252.    NOTES
  253.     This function may be called from interrupts.
  254.  
  255.    SEE ALSO
  256.  
  257.    BUGS
  258.  
  259.  
  260. timer.device/SubTime()                                   timer.device/SubTime()
  261.  
  262.    NAME
  263.     SubTime -- Subtract one time request from another.
  264.  
  265.    SYNOPSIS
  266.     SubTime( Dest, Source )
  267.              A0    A1
  268.  
  269.     void SubTime( struct timeval *, struct timeval *);
  270.  
  271.    FUNCTION
  272.     This routine subtracts one timeval structure from another.  The
  273.     results are stored in the destination (Dest - Source -> Dest)
  274.  
  275.     A0 and A1 will be left unchanged
  276.  
  277.    INPUTS
  278.     Dest, Source -- pointers to timeval structures.
  279.  
  280.    NOTES
  281.     This function may be called from interrupts.
  282.  
  283.    SEE ALSO
  284.     timer.device/AddTime(),
  285.     timer.device/CmpTime()
  286.  
  287.    BUGS
  288.  
  289.  
  290. timer.device/TR_ADDREQUEST                           timer.device/TR_ADDREQUEST
  291.  
  292.    NAME
  293.     TR_ADDREQUEST -- Submit a request to wait a period of time.
  294.  
  295.    FUNCTION
  296.     Ask the timer to wait a specified amount of time before
  297.     replying the timerequest.
  298.  
  299.     The message may be forced to finish early with an
  300.     AbortIO()/WaitIO() pair.
  301.  
  302.    TIMER REQUEST
  303.     io_Message      mn_ReplyPort initialized
  304.     io_Device       preset by timer in OpenDevice
  305.     io_Unit         preset by timer in OpenDevice
  306.     io_Command      TR_ADDREQUEST
  307.     io_Flags        IOF_QUICK permitted (but ignored)
  308.     tr_time         a timeval structure specifying how long the 
  309.                         device will wait before replying
  310.  
  311.    RESULTS
  312.     tr_time         will contain junk
  313.  
  314.    NOTES
  315.     This function may be called from interrupts.
  316.  
  317.    SEE ALSO
  318.     timer.device/AbortIO(),
  319.     timer.device/TimeDelay(),
  320.  
  321.    BUGS
  322.  
  323.  
  324. timer.device/TR_GETSYSTIME                           timer.device/TR_GETSYSTIME
  325.  
  326.    NAME
  327.     TR_GETSYSTIME -- get the system time.
  328.  
  329.    FUNCTION
  330.     Ask the system what time it is.  The system time starts off at
  331.     zero at power on, but may be initialized via the TR_SETSYSTIME
  332.     call.
  333.  
  334.     System time is monotonically increasing, and guaranteed to be
  335.     unique (except when the system time is set backwards).
  336.  
  337.    TIMER REQUEST
  338.     io_Message      mn_ReplyPort initialized
  339.     io_Device       preset by timer in OpenDevice
  340.     io_Unit         preset by timer in OpenDevice
  341.     io_Command      TR_GETSYSTIME
  342.     io_Flags        IOF_QUICK permitted
  343.  
  344.    RESULTS
  345.     tr_time         a timeval structure with the current system
  346.                         time
  347.  
  348.    NOTES
  349.     This function may be called from interrupts.
  350.  
  351.    SEE ALSO
  352.     timer.device/TR_SETSYSTIME,
  353.     timer.device/GetSysTime(),
  354.  
  355.    BUGS
  356.  
  357.  
  358. timer.device/TR_SETSYSTIME                           timer.device/TR_SETSYSTIME
  359.  
  360.    NAME
  361.     TR_SETSYSTIME -- Set the system time.
  362.  
  363.    FUNCTION
  364.     Set the system idea of what time it is.  The system starts out
  365.     at time "zero" so it is safe to set it forward to the real
  366.     time.  However, care should be taken when setting the time
  367.     backwards.  System time is generally expected to monotonically
  368.     increasing.
  369.  
  370.    TIMER REQUEST
  371.     io_Message      mn_ReplyPort initialized
  372.     io_Device       preset by timer in OpenDevice
  373.     io_Unit         preset by timer in OpenDevice
  374.     io_Command      TR_GETSYSTIME
  375.     io_Flags        IOF_QUICK permitted
  376.     tr_time         a timeval structure with the current system
  377.                         time
  378.  
  379.    RESULTS
  380.     tr_time         will contain junk
  381.  
  382.    NOTES
  383.     This function may be called from interrupts.
  384.  
  385.    SEE ALSO
  386.     timer.device/TR_GETSYSTIME,
  387.     timer.device/GetSysTime(),
  388.  
  389.    BUGS
  390.  
  391.  
  392.